1. About

Multisync is a multiplayer plugin designed for DarkBASIC Professional, utilizing the TCP protocol and the client/server networking model, created by me, Benjamin Wharton.

It has been completely rewritten from scratch since version 0.5, and some of its functionality is a little different. For full description on the changes, see the next subsection.

2. Converting from v0.5

One of the major changes is that message data is now read in the correct order (last in - last out).

Some of the command names have been changed since version 0.5, and are listed below, with the new command name following. It is also worth noting that words are seperated in all command names now.

• net join -> net connect
• net finish -> net disconnect
• net kill -> net kick
• net newplayer -> net player joined
• net get player state -> net player connected
• net set port local -> net set port
• net set port remote -> net set port
• net push char -> net put byte
• net push word -> net put word
• net push float -> net put float
• net pop char -> net get byte
• net pop word -> net get word
• net pop float -> net get float
• net get msginsize -> net get message remainder
• net get msgtotalsize -> net get message size
• net get msg -> net get message

The following commands have been removed, either due to redundancy or otherwise:
net receive, net forcekill, net get packetspersecond, net make buffers, net set buffers, net set port local*, net set port remote*, net seek in, net seek out, net get msgoutsize, net stack on, net stack off, net get msg amount.

* These have become a single command, net set port.

3. Changes in v1.4

* Fixed bug that was causing random crashes for some.
* Fixed cleanup routine to avoid memory leaks.
* Fixed flaw in message storing system.
* Added NET PUT MEMBLOCK and NET GET MEMBLOCK commands to deal with memblocks in messages (note that these can't be used in DBC). For DarkGDK and DBC users the functions NetPutData and NetGetData have been added to allow blocks of data to be handled in messages.
* Added new option to define the size of the write buffer.

1. General Tips

The commands NET HOST and NET CONNECT return a boolean value indicating whether the operation succeeded or not. It is recommended that you always check this value and take necessary measures if there is a failure.

When NET HOST or NET CONNECT fail, or you discover disconnection through use of NET CONNECTED, an error string can be obtained from NET GET ERROR. This error can be helpful in determining what went wrong. Relevant errors are listed under the commands in the command reference.

2. Serving

Starting a server can be accomplished by calling NET HOST, with the first parameter indicating the maximum amount of players you want the server to support. If a player tries to connect when the game is full, the connection will fail with the error GAME FULL.

To acknowledge new players in the game, NET PLAYER JOINED is called. This command returns the ID of the player who recently joined. The next time this command is called, it'll return the next player waiting to join (or 0 if there are none), so store the value returned if necessary.

To acknowledge players that have left the game, NET PLAYER LEFT is called. This command works in a similar way to the above command, except it indicated players that have disconnected.

3. Initializing a Connection

Connecting to a server is achieved by calling NET CONNECT, with the first parameter indicating the IP address of the server.

4. Processing Messages

Messages are constructed with a series of NET PUSH commands, up to 2048 bytes in total. You must read data in the same order as it was written. For instance, if you send an integer value and then send a string, the receiver must then read the integer value first and then the string.

The command NET GET MESSAGE is called to indicate if there is a new message, and to retrieve it for reading. It is recommended that you use a loop to read messages until NET GET MESSAGE returns 0. Below is some practical code for sending/receiving messages:

rem Message writing code
net put string "hello world"
net put byte 123
net send

rem Message reading code
while net get message()
	myString$ = net get string()
	myValue = net get byte()

	print myString$
	print myValue
endwhile

Note: In DBC, Multisync will not return strings larger than 256 bytes in size.

1. DBC Enhanced

It is possible to use Multisync from DarkBASIC Classic if you have the enhancements pack. The plugin is called via DLL commands, however a .dba file is included that allows you to call the commands like user functions.

Note: In order to test a server application programmed in DBC you must create an EXE and run it outside the editor, else problems may arise.

The following steps will allow you to compile an example application included with Multisync:
1. Copy Multisync.dll to the Example - Using in DBC Enhanced folder located in the examples directory.
2. Open server.dba and client.dba in DBC and create an executable for them both.
3. Execute the server outside of the editor, followed by the client (preferably outside of the editor also).

2. Communicating with Multisync using TCP

For the most part communicating with Multisync is easy because it uses almost no protocol on top of TCP. These are the things worth noting:

• When the client initially connects, it waits for 3 bytes of data from the server. The first unsigned short integer (2 bytes) is set to 0 if the client is allowed to join the game, else it is set to 1. The third byte is ignored at this time but must be transmitted anyway.
• Each message is prefixed with an unsigned short integer defining the size of the message.
• The ping message sent by the server, and the ping response sent by the client, consists of 2 bytes set to zero.
• Data is sent in little-endian (Intel) format.
• Strings sent and received are C-style ANSI strings.
• The maximum size of a message is 2048 bytes not including the prefix.